home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / cat3 / EnterFile.3 < prev    next >
Text File  |  1994-09-20  |  5KB  |  133 lines
  1.  
  2.  
  3.  
  4. Tcl_EnterFile(3)     Tcl Library Procedures                   7.0
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      Tcl_EnterFile, Tcl_GetOpenFile, Tcl_FilePermissions -  mani-
  12.      pulate the table of open files
  13.  
  14. SYNOPSIS
  15.      #include <tcl.h>
  16.  
  17.      Tcl_EnterFile(_i_n_t_e_r_p, _f_i_l_e, _p_e_r_m_i_s_s_i_o_n_s)
  18.  
  19.      int
  20.      Tcl_GetOpenFile(_i_n_t_e_r_p, _s_t_r_i_n_g, _w_r_i_t_e, _c_h_e_c_k_U_s_a_g_e, _f_i_l_e_P_t_r)
  21.  
  22.      int
  23.      Tcl_FilePermissions(_f_i_l_e)
  24.  
  25. ARGUMENTS
  26.      Tcl_Interp   *_i_n_t_e_r_p      (in)      Tcl   interpreter   from
  27.                                          which   file  is  to  be
  28.                                          accessed.
  29.  
  30.      FILE         *_f_i_l_e        (in)      Handle for file that  is
  31.                                          to  become accessible in
  32.                                          _i_n_t_e_r_p.
  33.  
  34.      int          _p_e_r_m_i_s_s_i_o_n_s  (in)      OR-ed   combination   of
  35.                                          TCL_FILE_READABLE    and
  36.                                          TCL_FILE_WRITABLE; indi-
  37.                                          cates  whether  _f_i_l_e was
  38.                                          opened  for  reading  or
  39.                                          writing or both.
  40.  
  41.      char         *_s_t_r_i_n_g      (in)      String identifying file,
  42.                                          such as stdin or file4.
  43.  
  44.      int          _w_r_i_t_e        (in)      Non-zero means the  file
  45.                                          will  be  used for writ-
  46.                                          ing, zero means it  will
  47.                                          be used for reading.
  48.  
  49.      int          _c_h_e_c_k_U_s_a_g_e   (in)      If  non-zero,  then   an
  50.                                          error  will be generated
  51.                                          if   the   file   wasn't
  52.                                          opened  for  the  access
  53.                                          indicated by _w_r_i_t_e.
  54.  
  55.      FILE         **_f_i_l_e_P_t_r    (out)     Points to word in  which
  56.                                          to store pointer to FILE
  57.                                          structure for  the  file
  58.                                          given by _s_t_r_i_n_g.
  59. _________________________________________________________________
  60.  
  61.  
  62.  
  63. Tcl                                                             1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Tcl_EnterFile(3)     Tcl Library Procedures                   7.0
  71.  
  72.  
  73.  
  74. DESCRIPTION
  75.      These procedures provide access to Tcl's file naming mechan-
  76.      ism.   Tcl_EnterFile  enters  an  open  file into Tcl's file
  77.      table so that it can be accessed  using  Tcl  commands  like
  78.      gets,  puts,  seek, and close.  It returns in _i_n_t_e_r_p->_r_e_s_u_l_t
  79.      an identifier such as file4 that can be used to refer to the
  80.      file in subsequent Tcl commands.  Tcl_EnterFile is typically
  81.      used to implement new Tcl commands that open sockets, pipes,
  82.      or  other kinds of files not already supported by the built-
  83.      in commands.
  84.  
  85.      Tcl_GetOpenFile takes as argument a file identifier  of  the
  86.      form  returned  by  the  open  command  or Tcl_EnterFile and
  87.      returns at *_f_i_l_e_P_t_r a pointer to the FILE structure for  the
  88.      file.  The _w_r_i_t_e argument indicates whether the FILE pointer
  89.      will be used for reading or writing.  In some cases, such as
  90.      a  file  that  connects  to a pipeline of subprocesses, dif-
  91.      ferent FILE pointers will be returned for reading and  writ-
  92.      ing.   Tcl_GetOpenFile normally returns TCL_OK.  If an error
  93.      occurs in Tcl_GetOpenFile (e.g. _s_t_r_i_n_g didn't make any sense
  94.      or  _c_h_e_c_k_U_s_a_g_e  was  set  and the file wasn't opened for the
  95.      access specified by _w_r_i_t_e) then TCL_ERROR  is  returned  and
  96.      _i_n_t_e_r_p->_r_e_s_u_l_t will contain an error message.  If _c_h_e_c_k_U_s_a_g_e
  97.      is zero and the file wasn't opened for the access  specified
  98.      by _w_r_i_t_e, then the FILE pointer returned at *_f_i_l_e_P_t_r may not
  99.      correspond to _w_r_i_t_e.
  100.  
  101.      Tcl_FilePermissions returns an OR-ed combination of the mask
  102.      bits TCL_FILE_READABLE and TCL_FILE_WRITABLE; these indicate
  103.      whether the given file was opened for reading or writing  or
  104.      both.   If _f_i_l_e does not refer to a file in Tcl's file table
  105.      then -1 is returned.
  106.  
  107.  
  108. KEYWORDS
  109.      file table, permissions, pipeline, read, write
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129. Tcl                                                             2
  130.  
  131.  
  132.  
  133.